/**
 * @file SimpleCDCTL.h
 * @brief CDCTL01A芯片驱动头文件
 * @details 为Arduino平台提供CDCTL01A芯片的完整驱动接口
 *          支持硬件加速的CDBUS通信，包括：
 *          - SPI接口通信
 *          - 寄存器配置
 *          - 数据帧收发
 *          - 中断处理
 *          - MAC地址管理
 *          - 波特率设置
 *          - 地址过滤
 * 
 * @author 修改团队：mastwet@Undefine Innovation
 * @date 2024
 * @copyright MIT License
 * 
 * @section 硬件连接
 * CDCTL01A芯片需要以下连接：
 * - SPI接口：MISO, MOSI, SCK
 * - 片选引脚：CS（用户指定）
 * - 中断引脚：INT（用户指定）
 * - 电源：3.3V或5V（根据芯片规格）
 * - 地线：GND
 * 
 * @section 使用示例
 * @code
 * #include <SimpleCDCTL.h>
 * 
 * SimpleCDCTL cdctl(10, 2);  // CS=10, INT=2
 * 
 * void setup() {
 *     cdctl.begin(0x01, 1000000);  // MAC地址=0x01, 波特率=1Mbps
 * }
 * 
 * void loop() {
 *     if (cdctl.available()) {
 *         uint8_t buffer[64];
 *         uint8_t len = cdctl.read(buffer, sizeof(buffer));
 *         // 处理接收到的数据
 *     }
 * }
 * @endcode
 * 
 * @warning 使用前需要正确连接所有引脚
 * @warning SPI接口需要硬件支持
 * @warning 最大数据帧长度为64字节
 */

#ifndef SIMPLE_CDCTL_H
#define SIMPLE_CDCTL_H

#include <Arduino.h>
#include <SPI.h>
#include "cdbus.h"

/**
 * @defgroup CDCTL_Registers CDCTL01A寄存器定义
 * @brief CDCTL01A芯片的寄存器地址和位定义
 * @{
 */

/**
 * @name 寄存器地址定义
 * @{
 */
#define CDREG_CFG_0         0x00    /**< 配置寄存器0 */
#define CDREG_CFG_1         0x01    /**< 配置寄存器1 */
#define CDREG_MAC           0x02    /**< MAC地址寄存器 */
#define CDREG_BAUD_L        0x03    /**< 波特率低字节寄存器 */
#define CDREG_BAUD_H        0x04    /**< 波特率高字节寄存器 */
#define CDREG_FILTER_M0     0x05    /**< 过滤器0掩码寄存器 */
#define CDREG_FILTER_M1     0x06    /**< 过滤器1掩码寄存器 */
#define CDREG_TX_CTRL       0x07    /**< 发送控制寄存器 */
#define CDREG_RX_CTRL       0x08    /**< 接收控制寄存器 */
#define CDREG_STATUS        0x09    /**< 状态寄存器 */
#define CDREG_INT_MASK      0x0A    /**< 中断屏蔽寄存器 */
/** @} */

/**
 * @name 配置位定义
 * @{
 */
#define CDBIT_MODE_ARB        0x00    /**< 仲裁模式 */
#define CDBIT_MODE_BREAK      0x80    /**< 中断同步模式 */
#define CDBIT_RX_RST_ALL      0x80    /**< 接收器复位 */
#define CDBIT_TX_ABORT        0x40    /**< 发送中止 */
/** @} */

/**
 * @name 状态位定义
 * @{
 */
#define CDSTAT_RX_PENDING     0x01    /**< 接收数据待处理 */
#define CDSTAT_TX_PENDING     0x02    /**< 发送数据待处理 */
#define CDSTAT_CD             0x04    /**< 载波检测 */
/** @} */

/** @} */  /* CDCTL_Registers */

/**
 * @class SimpleCDCTL
 * @brief CDCTL01A芯片驱动类
 * @details 提供CDCTL01A芯片的完整驱动功能
 *          支持SPI通信、寄存器配置、数据收发等
 */
class SimpleCDCTL {
public:
    /**
     * @brief 构造函数
     * @param cs_pin 片选引脚（Chip Select）
     * @param int_pin 中断引脚（Interrupt）
     * @details 创建CDCTL01A驱动对象实例
     * 
     * @note CS引脚必须为数字输出引脚
     * @note INT引脚必须为数字输入引脚，支持中断功能
     */
    SimpleCDCTL(uint8_t cs_pin, uint8_t int_pin);
    
    /**
     * @defgroup Initialization 初始化函数
     * @{
     */
    
    /**
     * @brief 初始化CDCTL01A芯片
     * @param mac_address 设备MAC地址（0-255）
     * @param baud_rate 通信波特率（默认1Mbps）
     * @return true初始化成功，false初始化失败
     * @details 完成芯片初始化、寄存器配置、中断设置
     * 
     * @note 必须在调用其他函数前调用此函数
     * @note 建议使用115200或更高的波特率
     */
    bool begin(uint8_t mac_address, uint32_t baud_rate = 1000000);
    
    /**
     * @brief 关闭CDCTL01A芯片
     * @details 禁用接收器并重置初始化状态
     *          释放相关资源
     */
    void end();
    
    /** @} */  /* Initialization */
    
    /**
     * @defgroup Configuration 配置函数
     * @{
     */
    
    /**
     * @brief 设置MAC地址
     * @param mac 设备地址（0-255）
     * @details 配置CDCTL01A芯片的设备地址
     * 
     * @note 地址0为广播地址，建议使用1-254
     */
    void setMacAddress(uint8_t mac);
    
    /**
     * @brief 设置通信波特率
     * @param low_baud 低速波特率
     * @param high_baud 高速波特率（可选，默认0使用low_baud）
     * @details 根据系统时钟计算波特率分频系数
     * 
     * @note 基于48MHz系统时钟计算
     */
    void setBaudRate(uint32_t low_baud, uint32_t high_baud = 0);
    
    /**
     * @brief 设置地址过滤器
     * @param filter0 过滤器0掩码
     * @param filter1 过滤器1掩码
     * @details 配置数据帧接收过滤器
     * 
     * @note 0xFF表示接收所有地址
     */
    void setFilter(uint8_t filter0, uint8_t filter1);
    
    /**
     * @brief 设置工作模式
     * @param break_sync true为中断同步模式，false为仲裁模式（默认）
     * @details 配置CDCTL01A的工作模式
     * 
     * @note 仲裁模式：标准CDBUS通信
     * @note 中断同步模式：用于特殊同步场景
     */
    void setMode(bool break_sync = false);
    
    /** @} */  /* Configuration */
    
    /**
     * @defgroup CDBUS_Interface CDBUS接口函数
     * @{
     */
    
    /**
     * @brief 检查是否有数据可读取
     * @return true有数据，false无数据
     * @details 通过中断引脚状态判断是否有数据
     */
    bool available();
    
    /**
     * @brief 读取接收到的数据
     * @param buffer 数据缓冲区
     * @param max_length 最大读取长度
     * @return 实际读取的数据长度
     * @details 从接收缓冲区读取数据帧
     * 
     * @note 读取完成后自动回收帧缓冲区
     */
    uint8_t read(uint8_t *buffer, uint8_t max_length);
    
    /**
     * @brief 发送数据
     * @param data 数据缓冲区
     * @param length 数据长度
     * @return true发送成功，false发送失败
     * @details 构造完整CDBUS数据帧并发送
     * 
     * @note 最大支持64字节数据
     */
    bool write(const uint8_t *data, uint8_t length);
    
    /** @} */  /* CDBUS_Interface */
    
    /**
     * @defgroup Status 状态函数
     * @{
     */
    
    /**
     * @brief 获取芯片状态
     * @return 状态寄存器值
     * @details 读取CDCTL01A的状态寄存器
     *          包含接收、发送、错误等状态信息
     */
    uint8_t getStatus();
    
    /**
     * @brief 检查初始化状态
     * @return true已初始化，false未初始化
     */
    bool isInitialized() { return _initialized; }
    
    /** @} */  /* Status */
    
    /**
     * @defgroup Register_Access 寄存器访问函数
     * @{
     */
    
    /**
     * @brief 读取寄存器
     * @param reg 寄存器地址（0-127）
     * @return 寄存器值
     * @details 通过SPI接口读取CDCTL01A寄存器
     * 
     * @warning 请确保寄存器地址有效
     */
    uint8_t readRegister(uint8_t reg);
    
    /**
     * @brief 写入寄存器
     * @param reg 寄存器地址（0-127）
     * @param value 寄存器值
     * @details 通过SPI接口写入CDCTL01A寄存器
     * 
     * @warning 请确保寄存器地址和值有效
     */
    void writeRegister(uint8_t reg, uint8_t value);
    
    /** @} */  /* Register_Access */
    
    /**
     * @defgroup Interrupt 中断处理函数
     * @{
     */
    
    /**
     * @brief 处理中断
     * @details 处理CDCTL01A芯片中断
     *          通常在ISR中调用此函数
     * 
     * @note 需要读取状态寄存器并处理相应事件
     */
    void handleInterrupt();
    
    /**
     * @brief 检查中断状态
     * @return true有中断，false无中断
     * @details 通过INT引脚状态判断是否产生中断
     */
    bool interruptPending();
    
    /** @} */  /* Interrupt */
    
    /**
     * @defgroup CDNET_Interface CDNET接口函数
     * @{
     */
    
    /**
     * @brief 获取CDBUS设备接口
     * @return CDBUS设备结构体指针
     * @details 获取底层CDBUS设备接口，用于CDNET协议栈
     * 
     * @note 用于与CDNET协议栈集成
     */
    cd_dev_t* getCDBUSDevice() { return &_cd_dev; }
    
    /** @} */  /* CDNET_Interface */

private:
    /**
     * @defgroup Private_Members 私有成员
     * @{
     */
    
    uint8_t _cs_pin;        /**< 片选引脚 */
    uint8_t _int_pin;       /**< 中断引脚 */
    bool _initialized;      /**< 初始化标志 */
    
    /**
     * @brief CDBUS设备结构体
     * @details 用于与底层CDBUS协议栈交互
     */
    cd_dev_t _cd_dev;
    
    /**
     * @brief 帧缓冲区管理
     * @{
     */
    static const uint8_t FRAME_MAX = 8;     /**< 最大帧缓冲区数量 */
    cd_frame_t _frames[FRAME_MAX];          /**< 帧缓冲区数组 */
    list_head_t _free_head;                 /**< 空闲帧链表头 */
    /** @} */
    
    /**
     * @defgroup Private_Methods 私有方法
     * @{
     */
    
    /**
     * @brief SPI数据传输
     * @param tx_data 发送数据缓冲区
     * @param rx_data 接收数据缓冲区
     * @param length 数据长度
     * @details 执行SPI全双工数据传输
     */
    void spiTransfer(uint8_t *tx_data, uint8_t *rx_data, uint8_t length);
    
    /**
     * @brief 初始化帧管理
     * @details 初始化空闲帧链表和缓冲区
     */
    void initializeFrames();
    
    /**
     * @brief 复位芯片
     * @details 通过寄存器复位CDCTL01A芯片
     */
    void resetChip();
    
    /**
     * @brief CDBUS回调函数 - 获取接收帧
     * @param cd_dev CDBUS设备指针
     * @return 接收到的帧指针，无数据返回NULL
     * @details 静态回调函数，用于底层协议栈获取接收帧
     */
    static cd_frame_t* getRxFrame(cd_dev_t *cd_dev);
    
    /**
     * @brief CDBUS回调函数 - 发送帧
     * @param cd_dev CDBUS设备指针
     * @param frame 待发送的帧指针
     * @details 静态回调函数，用于底层协议栈发送帧
     */
    static void putTxFrame(cd_dev_t *cd_dev, cd_frame_t *frame);
    
    /** @} */  /* Private_Methods */
    
    /** @} */  /* Private_Members */
};

/**
 * @mainpage SimpleCDCTL库文档
 * 
 * @section intro 简介
 * SimpleCDCTL是一个为Arduino平台设计的CDCTL01A芯片驱动库。
 * 它提供了完整的硬件加速CDBUS通信功能。
 * 
 * @section features 特性
 * - 支持SPI接口通信
 * - 硬件加速数据收发
 * - 自动CRC校验
 * - 地址过滤功能
 * - 中断驱动接收
 * - 灵活的波特率配置
 * - 与CDNET协议栈兼容
 * 
 * @section requirements 要求
 * - Arduino IDE 1.8+ 或 PlatformIO
 * - 支持SPI的Arduino开发板
 * - CDCTL01A芯片
 * - 正确的硬件连接
 */

#endif // SIMPLE_CDCTL_H